\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename planter.info
@settitle Planter
@c %**end of header

@copying
Copyright (C) 2014 Klaatu
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end copying

@titlepage
@title Planter
     
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
     
@c Output the table of contents at the beginning.
@contents

@ifnottex
@node Top
@top Planter
     
Keeping assets organised for artistic endeavours is always difficult,
so establishing a directory tree that provides structure and order to
a multimedia project is important to the creation process, and vital
to the integrity of the archived project.  However, creating a complex
directory tree each time a new project is created can be confusing and
tedious.

The sales pitch:

Say you are going to write a book called ``Private
Property''. With Planter, you create a project directory tree:

# planter privateProperty

and a directory tree with all the folders you need to keep your project
organised is created in your current directory. You spend some time
writing, you produce a brilliant[ly strange] sci fi novel and suddenly
realise that you need to design a cover. Luckily, thanks to Planter, you already
have a directory tree for graphics, fonts, and final output. If you
decide later to expand privateProperty into an audio book, you already
have the structure for a full audio production. Want to make it into a
movie? graphic novel? it's all ready to be populated in your project tree.

And when you have finished, you can archive the privateProperty
folder, secure in the knowledge that should you ever need to return to
it years from now for a special anniversary release, you have every
asset required to resume work on the project. No more missing assets!


@end ifnottex
     
@menu
* Introduction::        Introduction
* Installation::        Installing
* Usage::               Using
* Customizing::         Customizing
* FAQs::                Frequently Asked Questions
* Index::               Complete index.
@end menu


@node Introduction
@chapter Introduction

@cindex about

Planter creates a standardised, full directory tree for multimedia
content creators.

Planter can be used as a text-based command in a shell, or with a GUI.

Planter requires three pieces of infomation:

@enumerate
@item
A project name, which will serve as the top level directory.

@item
A location where the new project tree will be placed (such as your home directory, or your music folder, or an external drive).

@item
The location of shared assets. If you are working in a group, then this might be a location on a mapped network drive. If you are working alone or only locally, then it might be /usr/local/share.
@end enumerate

All of these options can be set from the shell or from the GUI, or a
combination of both.


@node Installation
@chapter Installation

@cindex installation

If you're reading this, you have probably already installed
Planter. If not, then the these are some technical details about
Planter and what you need to know to install it.

@enumerate
@item
Planter can use either Python2.7.x or Python3.x. 

@item
Planter uses dbus for notifications.

@item
By default, KNotify is used for notifications. Planter will
automatically fall back to easygui if KNotify is not available, but if
you plan on doing that, then make sure you have easygui available.

@item
The executable file, 'planter', can be placed anywhere on the
system, such as /usr/bin or /usr/local/bin. The file it requires to
run is tree.list, and that should be placed in
/etc/planter.
@end enumerate

The default behaviour of Planter, when launched from the GUI, is to
bring up the GUI interface and help a let a new user choose their
options. You can control default behaviour by modifying the
planter.desktop file, which is installed to
/usr/share/applcations. The .desktop file by default launches Planter
with notifications turned on, and with the usual default locations and
paths, You may override all of these on a system level by entering
your preferences into the command that the .desktop file issues.

However, Planter can also operate independently of its GUI, so you may also
map it to a keyboard shortcut, or to a contextual menu in your file
manager, or just use it from the shell.


@node Usage
@chapter Usage

@cindex using, howto, tutorial

The simplest use of Planter is to issue (or run) it without changing
or specifying anything:

$ planter

This creates the default directory tree with the default project name,
in the current directory.

Or you can use these arguments:

@enumerate
@item ProjectName
The project name is your own name for the project that you are about
to create. If you are making an animation called ``PosixWar'' then your
project name could be, for instance, ``posixWar''. It is best practise to prefer camelCase over spaces, and to avoid special, non-alphanumeric characters.

The project name requires no flag in the shell:

$ planter posixWar

If no project name is provided, then the default project name (factory
setting for this is ``newSlackermediaProject'') is used.

@item -d, --destination
Where you want your project tree to be placed. This should be a
directory that exists on your drive. The default is the current directory.

@item -s, --shared
The location of shared media assets. This is most useful for large
organisations with a library of shared files, but it can be useful even for the
solitary artist or small group of artists.

The convention in Slackermedia is to place common read-only assets,
such as sample banks, soundfonts, extra fonts, company logos, models,
textures, clip art, and so on, in /usr/local/shared/artkit. These are
assets that are assumed to be standard assets in your organisation and
not specific to just one project; for example, several musical pieces
may all contain sounds from the same sample bank, so if you set the
location of your samples to a standardised location, you will never
again open the track you were working on and discover that your
sampler can't find its sound files. And likewise, if you get a new
computer and all of your paths have changed, as long as you place
these assets in the same location, all of your projects will still
work.

If you do not want to use /usr/local/share/artkit as the location for
common files, then change the value of the shared location so that it
points to where you do keep assets which span projects.

@item -g, --gui
Launches Planter in its GUI mode, in case you do not want to use the shell.

@item -t, --type
Project type to create. Defaults to the default project in the tree.list
config file.

@item -q, --quiet
Normally, after Planter creates a directory tree, it alerts you in
your computer's notification area. Using this option turns off
Planter's notification system.

@item -c, --config
Planter's default template seeks to be everything for everyone,
specifically because you rarely know in advance how complex your art
project is going to become. Directories are basically free, so it
doesn't cost anything to generate as many reasonable directory trees
as you think a project is going to ever need.

However, if you prefer to use customised templates on a per project
(or per project-type) basis, you can generate any number of template
files as you like, and point Planter at them at runtime.

It defaults to the standard /etc/planter/tree.list
@end enumerate

@node Customizing
@chapter Customizing

Having been written in Python, Planter is easy to modify on its lowest
level, if you want to re-programme it entirely. However, you do not
need to be a programmer for common customisations.

Planter creates its project trees based on the contents of its default
template file, called ``tree.list''.

The default tree.list has sample project structures in it, but you are free
to change the template to fit your needs. You may also create
user-specific tree.list files and point Planter to them using the
``--config'' flag.

The file /etc/planter/tree.list is written in YAML, a simple and
intuitive config format. Its basic structure consists of an arbitrary
template name followed by a list of directories and links contained in
that project. Using a project intended for a music video, here is an
example:

musicvideo:
  - mkdir: video
  - mkdir: sound
  - mkdir: sound/sample
  - mkdir: font
  - copyfile: %COMMON%/everylicense/cc/cc-by-sa.md:LICENSE
  - symlink: %COMMON%/fonts/foo.ttf:font/foo.ttf
  - symdir: %COMMON%/sample:sound/sample

@enumerate
@item mkdir 
A mkdir lines tells Planter to make a new directory, and then the name
of that directory. For instance:

mkdir:video 
mkdir:video/thumbnails 
mkdir:video/video

These lines create a ``video'' directory, inside of which are two
directories, one called ``thumbnails'' and the other ``video''.

Remember that this is a template, so all paths are relative to the
project name that the user mill give to Planter at runtime. In other
words, Planter creates the folder structure defined in tree.list
INSIDE the top level directory called ``newSlackermediaProject'', or
whatever name you tell Planter to use when you run Planter. 

A project name should never appear in tree.list itself.

@item symdir
A symdir line creates a symlink (sometimes known as an "alias" or
"shortcut") to an existing directory containing shared assets. There
are two kinds of symlink lines:

symdir:graphics:video/graphics

creates a symlink in the video folder called ``graphics'', which
points to the graphics folder in the same project. This makes sure
that the same data is not being duplicated so that, for instance, the
video editor is using the same matte painting, title cards, and other
graphical elements that the graphic designer has been developing.

This line:

symdir:%COMMON%/samples:sound/samples

similarly creates a symlink from the sound directory called "samples",
pointing to a shared location (represented by the variable
%COMMON). In other words, %COMMON% gets replaced by Planter to
whatever the user tells it is the shared location (it is
/usr/local/share/artkit by default).

@item symlink
Same as symdir, but for individual files.

@item copyfile
In some cases, you may have sample documents, forms, logos, fonts, or
README files that you need to populate your default projects with. If
you find yourself doing this, you probably should move all of these
assets to a shared location (that would be the ``right way'' to do
it) but just in case you have a valid reason for not using a symlink
to a shared location, you may use the copyfile function.

This line:

copyfile:docs/legal/release.odt:production/forms/release.odt

copies the file ``release.odt'' from the
currentDirectory/docs/legal to
projectName/production/forms/release.odt

This is undocumented in the man page because it really should not be
over-used. To repeatedly copy lots of files around your filesystem,
there are better scriptable POSIX tools.
@end enumerate

You are free to add or subtract or modify the tree.list as much as you
see fit. Planter does nothing more than create the structure defined
in tree.list, so as long as you use the same format, Planter will work
as expected.

@node FAQs
@chapter FAQs

@cindex faq

Here are some answers to questions:

@enumerate Q
@item
Mhy not just use ``mkdir -p''?

@enumerate A
@item
You can do that, and it can be scripted or aliased so that you achieve
exactly the same functionality without resorting to Python and PyQt,
and so on.

@end enumerate
@end enumerate

@enumerate Q
@item
How to I archive a project?

@enumerate A
@item
One of the main goals of Planter is to preserve a project for all time
and eternity (short of imaging your entire hard drive).  Mostly,
Planter uses internal referencing so that projects stay
self-contained. But that is not always the case, if you have common
assets.

There are two ways to tackle this: one is to live with lots of
duplication, and the other is to be modular.

If you can live with duplicating common assets everytime you archive a
project, then all you need to do is:

$ tar chvf myProject.tar myProject

The -h flag in the tar command dereferences symlinked files, copying
anything that is linked into the archive. 

That's fine if you only have a few common files, but if you have an
entire data center of a media library that all of your projects use
bits and pieces from, then copying it is prohibitive and also
redundant.

If that is the case, then use tar normally:

$ tar cvf myProject.tar myProject

and all symlinks are preserved as symlinks. Now save ONE master copy
of your media library, and you have everything you need for your
projects to untar and run as if they'd never been archived.

@end enumerate
@end enumerate

@enumerate Q
@item
Mhy doesn't Planter have an archive option?
@enumerate A
@item
Planter is a project structure generator, not an archiver. So many
good and reliable tools, like tar, exist for archiving that I did not
want to try to duplicate them. I trust tar a lot more than I trust me
to reimplement it just for the sake of having everything in one tool. 
@end enumerate
@end enumerate

@enumerate Q
@item
How can I contact the Planter team?
@enumerate A
@item
Klaatu at klaatu@@member.fsf.org
Seth at seth@@opensource.com
Jess at jlweichler@@gmail.com
@end enumerate
@end enumerate


@c END

@node Index
@unnumbered Index
     
@printindex cp
     
@bye
